home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 42 / Amiga Format AFCD42 (Issue 126, Aug 1999).iso / -serious- / misc / identify / identify_dev / developer / identify.doc < prev    next >
Text File  |  1999-05-14  |  28KB  |  832 lines
  1. TABLE OF CONTENTS
  2.  
  3. identify.library/IdAlert
  4. identify.library/IdEstimateFormatSize
  5. identify.library/IdExpansion
  6. identify.library/IdFormatString
  7. identify.library/IdFunction
  8. identify.library/IdHardware
  9. identify.library/IdHardwareNum
  10. identify.library/IdHardwareUpdate
  11.  
  12. identify.library/IdAlert
  13.  
  14.    NAME
  15.         IdAlert - get description of an alert (V3)
  16.  
  17.    SYNOPSIS
  18.         Error = IdAlert(Code,TagList)
  19.         D0.l            D0.l   A0.l
  20.  
  21.         LONG IdAlert(ULONG, struct TagItem *);
  22.  
  23.         Error = IdAlertTags(Code,Tag1,...)
  24.  
  25.         LONG IdAlertTags(ULONG, ULONG,...);
  26.  
  27.    FUNCTION
  28.         Get a human readable description of the alert ('Guru') code.
  29.  
  30.    INPUTS
  31.         Code          -- (ULONG) alert code, as defined in exec/alerts.h
  32.  
  33.         TagList       -- (struct TagItem *) tags that describe further
  34.                          options.
  35.  
  36.    RESULT
  37.         Error         -- (LONG) error code, or 0 if everything went fine.
  38.  
  39.    TAGS
  40.         IDTAG_DeadStr           -- (STRPTR) Alert type string (deadend or
  41.                 recoverable). You may skip this tag if you do not want to get
  42.                 the string.
  43.  
  44.         IDTAG_SubsysStr         -- (STRPTR) String of the subsystem that caused
  45.                 the alert (CPU, exec.library, ...). You may skip this tag if you
  46.                 do not want to get the string.
  47.  
  48.         IDTAG_GeneralStr        -- (STRPTR) General alert cause. You  may skip
  49.                 this tag if you do not want to get the string.
  50.  
  51.         IDTAG_SpecStr           -- (STRPTR) Specified alert cause. You may skip
  52.                 this tag if you do not want to get the string.
  53.  
  54.         IDTAG_StrLength         -- (UWORD) Maximum length of the string buffer,
  55.                 including termination. Defaults to 50.
  56.  
  57.         IDTAG_Localize          -- [V8] (BOOL) FALSE to get English strings
  58.                 only, TRUE for localized strings. This is useful for applications
  59.                 with English as only language. Defaults to TRUE.
  60.  
  61.    NOTE
  62.         This call is guaranteed to preserve all registers except D0.
  63.  
  64.    BUGS
  65.  
  66.    SEE ALSO
  67.  
  68. identify.library/IdEstimateFormatSize
  69.    NAME
  70.         IdEstimateFormatSize - estimate size of a format buffer (V11)
  71.  
  72.    SYNOPSIS
  73.         Length = IdEstimateFormatSize(String,Tags)
  74.          D0.l                          A0.l  A1.l
  75.  
  76.         ULONG IdEstimateFormatSize(STRPTR, struct TagItem *);
  77.  
  78.         Length = IdEstimateFormatSizeTags(String,Tag1,...)
  79.  
  80.         ULONG IdEstimateFormatSizeTags(STRPTR,ULONG,...);
  81.  
  82.    FUNCTION
  83.         Estimates the size of the buffer that will contain the output
  84.         of the format string when used on IdFormatString().
  85.  
  86.    INPUTS
  87.         String          -- (STRPTR) Format string
  88.         Tags            -- (struct TagItem *) Tags, currently NULL or
  89.                 TAG_DONE.
  90.  
  91.    RESULT
  92.         Length          -- (ULONG) Length of the buffer size that will
  93.                 be able to hold the entire result.
  94.  
  95.    NOTE
  96.         The returned size will be large enough to contain the result
  97.         of a IdFormatString(). It is not necessarily the size of the
  98.         resulting buffer (the result length of IdFormatString()).
  99.  
  100.         This call is guaranteed to preserve all registers except D0.
  101.  
  102.    BUGS
  103.  
  104.    SEE ALSO
  105.         IdHardware(), IdFormatString()
  106.  
  107. identify.library/IdExpansion
  108.  
  109.    NAME
  110.         IdExpansion - get name of expansion board (V3)
  111.  
  112.    SYNOPSIS
  113.         Error = IdExpansion(TagList)
  114.         D0.l                  A0.l
  115.  
  116.         LONG IdExpansion(struct TagItem *);
  117.  
  118.         Error = IdExpansionTags(Tag1,...)
  119.  
  120.         LONG IdExpansionTags(ULONG,...);
  121.  
  122.    FUNCTION
  123.         Gets the name and class of the expansion and it's manufacturer.
  124.  
  125.    INPUTS
  126.         TagList       -- (struct TagItem *) tags that describe further
  127.                          options.
  128.    RESULT
  129.         Error         -- (LONG) error code, or 0 if everything went fine.
  130.  
  131.                 IDERR_NOLENGTH  -- IDTAG_StrLength has been set to 0!
  132.                 IDERR_BADID     -- IDTAG_ManufID and IDTAG_ProdID were
  133.                         out of range or one of them was missing.
  134.                 IDERR_DONE      -- Checked all expansions using the
  135.                         IDTAG_Expansion tag. This is not really an error.
  136.                 IDERR_SECONDARY -- This expansion is secondary to a primary
  137.                         expansion entry.
  138.  
  139.    TAGS
  140.         IDTAG_ConfigDev         -- (struct ConfigDev *) ConfigDev structure
  141.                 containing all information. You should use this tag if ever
  142.                 possible, since there are more possibilities to recognize and
  143.                 distinguish between a board.
  144.  
  145.         IDTAG_ManufID           -- (UWORD) Manufacturer ID if ConfigDev is not
  146.                 provided. You must also provide IDTAG_ProdID!
  147.  
  148.         IDTAG_ProdID            -- (UBYTE) Product ID if ConfigDev is not
  149.                 provided. You must also provide IDTAG_ManufID!
  150.  
  151.         IDTAG_ManufStr          -- (STRPTR) Pointer to a buffer space for the
  152.                 manufacturer name. You may skip this tag if you do not want
  153.                 to get this string.
  154.  
  155.         IDTAG_ProdStr           -- (STRPTR) Pointer to a buffer space for the
  156.                 product name. You may skip this tag if you do not want to get
  157.                 this string.
  158.  
  159.         IDTAG_ClassStr          -- (STRPTR) Pointer to a buffer space for the
  160.                 product class. You may skip this tag if you do not want to get
  161.                 this string.
  162.  
  163.         IDTAG_StrLength         -- (UWORD) Buffer length, including
  164.                 termination. Defaults to 50.
  165.  
  166.         IDTAG_Expansion         -- [V6] (struct ConfigDev **) Use this tag to
  167.                 easily traverse through the expansion board list. Init the
  168.                 pointed variable with NULL. After each call, you will find
  169.                 the current ConfigDev pointer in this variable. If you are
  170.                 done, this function returns IDERR_DONE and the variable is set
  171.                 to NULL. See example.
  172.  
  173.         IDTAG_Secondary         -- [V7] (BOOL) If set to TRUE, identify will
  174.                 warn about secondary expansions. E.g. some graphic boards
  175.                 create more than one entry in the expansion list. Then, one
  176.                 entry is the primary entry, and any additional are secondary.
  177.                 This tag does only make sense when checking all mounted
  178.                 expansions. Defaults to FALSE. (See Bugs)
  179.  
  180.         IDTAG_ClassID           -- [V8] (ULONG *) The ULONG field will be filled
  181.                 with a numerical class ID of the expansion (see include file:
  182.                 IDCID_...). IMPORTANT: You MUST be prepared to get a number
  183.                 that does not match to any IDCID value. In this case, assume
  184.                 IDCID_MISC.
  185.  
  186.         IDTAG_Localize          -- [V8] (BOOL) FALSE to get English strings
  187.                 only, TRUE for localized strings. This is useful for applications
  188.                 with English as only language. Defaults to TRUE.
  189.  
  190.    EXAMPLE
  191.         To check all expansion boards, you may use this code:
  192.  
  193.         void PrintExpansions(void)
  194.         {
  195.           struct ConfigDev *expans = NULL;
  196.           char manuf[IDENTIFYBUFLEN];
  197.           char prod[IDENTIFYBUFLEN];
  198.           char pclass[IDENTIFYBUFLEN];
  199.  
  200.           while(!IdExpansionTags(
  201.                   IDTAG_ManufStr ,manuf,
  202.                   IDTAG_ProdStr  ,prod,
  203.                   IDTAG_ClassStr ,pclass,
  204.                   IDTAG_Expansion,&expans,
  205.                   TAG_DONE))
  206.           {
  207.             Printf("Current ConfigDev = 0x%08lx\n",expans);
  208.             Printf("  Manufacturer    = %s\n",manuf);
  209.             Printf("  Product         = %s\n",prod);
  210.             Printf("  Expansion class = %s\n\n",class);
  211.           }
  212.         }
  213.  
  214.    NOTE
  215.         If the manufacturer or the product is not known, the string will be
  216.         filled with its number.
  217.  
  218.         This call is guaranteed to preserve all registers except D0.
  219.  
  220.    BUGS
  221.         You must also provide IDTAG_ProdStr if you want to use IDTAG_Secondary.
  222.  
  223.         There are by far not all existing boards implemented. Please send
  224.         the manufacturer id and name and the products id, name and class
  225.         o